home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / arts / kmedia2.idl < prev    next >
Encoding:
Text File  |  2005-09-10  |  5.6 KB  |  243 lines
  1. /*
  2.  
  3. NEW KMedia2 layout:
  4. ===================
  5.  
  6. KMedia1 itself doesn't play anything. Instead it has a backend for every
  7. media type to play. It tells these backends: "start playing now", "stop
  8. playing now" and similar things (using libmediatool). So there is a backend
  9. for wave files, tacker files, midi files, etc., which all provide one
  10. common interface.
  11.  
  12. The idea is to keep everything the old KMedia1 interface could do, but to
  13. move to a new IPC architecture (MCOP).
  14.  
  15. That way, KMedia2 objects will be able to use the aRts streaming abilities.
  16. Of course, not every KMedia2 object will need these, but some of them. The
  17. result will be much nicer, if every of these objects can be treated in the
  18. standard "flow graph" way, like other aRts objects can.
  19.  
  20. The ultimate media player, which KMedia2 aims to be, should play midi,
  21. video, audio, etc. It is about seeing a file, choosing a component which
  22. might be able to decode it, and play it. So it is not about starting
  23. the right application, but about loading the right component.
  24.  
  25. This gives you the advantage that you can for instance reuse components
  26. even between quite different media types. It may for instance make sense
  27. to reuse a reverb effect to play midi, audio and video files.
  28.  
  29. */
  30.  
  31. #include "artsflow.idl"
  32.  
  33. module Arts {
  34.  
  35. enum poState {
  36.   posIdle,
  37.   posPlaying,
  38.   posPaused
  39. };
  40.  
  41. // use 2^n values here, since they can (should) be or'd together
  42. enum poCapabilities {
  43.   capSeek = 1,
  44.   capPause = 2
  45. };
  46.  
  47. /**
  48.  * KMedia2 time information
  49.  *
  50.  * This is a time value which contains either milliseconds & seconds, or
  51.  * a custom unit or both. It is a flexible time base.
  52.  *
  53.  * If a value isn't there, it is set to -1.
  54.  */
  55. struct poTime {
  56.     /**
  57.      * time it takes in seconds; -1 if no clock time known
  58.      */
  59.     long seconds;
  60.  
  61.     /**
  62.      * additional time in milliseconds (this doesn't contain all the time)
  63.      * -1 if no clock time known
  64.      */
  65.     long ms;
  66.  
  67.     /**
  68.      * some custom time information
  69.      * -1 if no custom time known
  70.      */
  71.     float custom;
  72.  
  73.     /**
  74.      * for instance for a tracker "pattern"
  75.      */
  76.     string customUnit;
  77. };
  78.  
  79. /**
  80.  * private part of the PlayObject API (don't use)
  81.  */
  82. interface PlayObject_private {
  83.     /**
  84.      * loads a file
  85.      */
  86.     boolean loadMedia(string filename);
  87. };
  88.  
  89. /**
  90.  * KMedia2 PlayObject - these can be used by Kaiman for instance
  91.  */
  92. interface PlayObject : PlayObject_private {
  93.     readonly attribute string description;
  94.     readonly attribute poTime currentTime;
  95.     readonly attribute poTime overallTime;
  96.     readonly attribute poCapabilities capabilities;
  97.     readonly attribute string mediaName;
  98.     readonly attribute poState state;
  99.  
  100.     /**
  101.      * starts playing the media
  102.      */
  103.     void play();
  104.     /**
  105.      * seeks to a specific time
  106.      */
  107.     void seek(poTime newTime); // could be handled by setting currentTime
  108.     /**
  109.      * pauses playing the media
  110.      */
  111.     void pause();
  112.     /**
  113.      * stop playing the media. Normally this function would called stop,
  114.      * but the name is reserved for the start/stop mechanism of the
  115.      * aRts objects.
  116.      */
  117.     void halt();
  118. };
  119.  
  120. /**
  121.  * use this to create new PlayObjects for media
  122.  */
  123. interface PlayObjectFactory {
  124.     /**
  125.      * creates a play object (or returns a null reference if this is not
  126.      * possible)
  127.      *
  128.      * @param filename the name of the file to create a play object for
  129.      */
  130.     PlayObject createPlayObject(string filename);
  131. };
  132.  
  133. /**
  134.  * UNSTABLE/EXPERIMENTAL!
  135.  */
  136. interface InputStream : SynthModule {
  137.     /**
  138.      * whether the stream is at the end of the input
  139.      */
  140.     readonly attribute boolean eof;
  141.  
  142.     /**
  143.      * total size of the stream in bytes
  144.      *  -1: unknown
  145.      */
  146.     readonly attribute long size;
  147.  
  148.     /**
  149.      * whether the stream can be seeked
  150.      */
  151.     readonly attribute boolean seekOk;
  152.  
  153.     /**
  154.      * this returns the new AGE of the stream, where AGE is defined as the
  155.      * number of bytes that have been sent since the stream exists
  156.      */
  157.     long seek(long position);
  158.  
  159.     /**
  160.      * the stream data
  161.      */
  162.     async out byte stream outdata;
  163. };
  164.  
  165. /**
  166.  * UNSTABLE/EXPERIMENTAL! Example stream for files.
  167.  */
  168. interface FileInputStream : InputStream {
  169.     attribute string filename;
  170.  
  171.     boolean open(string filename);
  172. };
  173.  
  174. interface StdoutWriter : SynthModule {
  175.     async in byte stream indata;
  176. };
  177.  
  178. interface StreamPlayObject : PlayObject {
  179.     /**
  180.      * prepares the playobject for the stream
  181.      */
  182.     boolean streamMedia(InputStream instream);
  183.  
  184.     /**
  185.      * last used inputstream
  186.      * it should never change
  187.      */
  188.      InputStream inputStream();
  189. };
  190.  
  191. /**
  192.  * Playobject with adjustable speed
  193.  */
  194. interface PitchablePlayObject {
  195.     /**
  196.      * speed relative to "original"/intended one
  197.      * (1.0=normal, 2.0=double ;-), 1.05=5% faster)
  198.      */
  199.     attribute float speed;
  200. };
  201.  
  202. /**
  203.  * KMedia2 VideoPlayObject - new interface for video support
  204.  *
  205.  * Some of the communication is done using the X11 protocol.
  206.  */
  207. interface VideoPlayObject {
  208.     /**
  209.      * video output window (active)
  210.      */
  211.     attribute long x11WindowId;
  212.     /**
  213.      * take a snapshot and draw it onto a pixmap
  214.      * returns the X11 pixmap ID or -1 on error
  215.      */
  216.     long x11Snapshot();
  217. };
  218.  
  219. /**
  220.  * Extended Version of PlayObjectFactory
  221.  */
  222. interface PlayObjectFactoryV2 : PlayObjectFactory {
  223.     /**
  224.      * creates a PlayObject
  225.      *
  226.      * @param url the url to create a play object for
  227.      * @param mimetype mimetype for the url
  228.      * @param createBUS specifies wheter to create the bus-uplink or not
  229.      */
  230.     PlayObject createPlayObjectForURL(string url, string mimetype, boolean createBUS);
  231.  
  232.     /**
  233.      * creates a StreamPlayObject (used internally!)
  234.      *
  235.      * @param instream specifies the InputStream
  236.      * @param mimetype mimetype for the InputStream
  237.      * @param createBUS specifies wheter to create the bus-uplink or not
  238.      */
  239.     PlayObject createPlayObjectForStream(InputStream instream, string mimetype, boolean createBUS);
  240. };
  241.  
  242. };
  243.